home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / mawk10.zip / MAWK.DOC < prev    next >
Text File  |  1991-10-05  |  40KB  |  1,123 lines
  1.  
  2.  
  3.  
  4. MAWK(1)                   USER COMMANDS                   MAWK(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      mawk - pattern scanning and text processing language
  10.  
  11.  
  12. SYNOPSIS
  13.      mawk [-F_s] 'program text' [file ...]
  14.      mawk [-F_s] -f program-file [file ...]
  15.      mawk -V
  16.  
  17.  
  18. DESCRIPTION
  19.      mawk is an interpreter for  the  AWK  Programming  Language.
  20.      The  AWK  language is useful for manipulation of data files,
  21.      text retrieval  and  processing,  and  for  prototyping  and
  22.      experimenting with algorithms.  mawk is a _n_e_w _a_w_k meaning it
  23.      implements the AWK language as defined in Aho, Kernighan and
  24.      Weinberger,  _T_h_e  _A_W_K  _P_r_o_g_r_a_m_m_i_n_g  _L_a_n_g_u_a_g_e, Addison-Wesley
  25.      Publishing, 1988.  (Hereafter refered to as the AWK book.)
  26.  
  27.      An AWK program is a sequence of _p_a_t_t_e_r_n {_a_c_t_i_o_n}  pairs  and
  28.      function  definitions.   Short  programs  are entered on the
  29.      command  line  usually  enclosed  in  '  '  to  avoid  shell
  30.      interpretation.   Longer programs can be read in from a file
  31.      with the -f option.  Data  input is read from  the  list  of
  32.      files  on  the  command line or from standard input when the
  33.      list is empty.  The input is broken into records  as  deter-
  34.      mined by the record separator variable, RS.  Initially, RS =
  35.      "\n" and records are synonymous with lines.  Each record  is
  36.      compared against each _p_a_t_t_e_r_n and if it matches, the program
  37.      text for {_a_c_t_i_o_n} is executed.
  38.  
  39.  
  40. OPTIONS
  41.      -F_s  Set the field separator, FS, to string _s.
  42.  
  43.  
  44.      -f file
  45.           Read the program text from file  instead  of  from  the
  46.           command line.
  47.  
  48.  
  49.      -V   mawk writes its version and copyright notice to  stdout
  50.           and  internal limits to stderr and exits 0.  The inter-
  51.           nal limits can be changed by recompilation.
  52.  
  53.      The -f option must be last and when the -V option is  recog-
  54.      nized the rest of the command line is ignored.
  55.  
  56.  
  57. THE AWK LANGUAGE
  58.   1. Program structure
  59.      An AWK program is a sequence of _p_a_t_t_e_r_n {_a_c_t_i_o_n}  pairs  and
  60.  
  61.  
  62.  
  63. Version 1.0         Last change: Sep 14 1991                    1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MAWK(1)                   USER COMMANDS                   MAWK(1)
  71.  
  72.  
  73.  
  74.      user function definitions.
  75.  
  76.      A pattern can be:
  77.           BEGIN
  78.           END
  79.           expression
  80.           /regular expression/
  81.           ( pattern )
  82.           ! pattern
  83.           pattern || pattern
  84.           pattern && pattern
  85.           pattern , pattern    (a range pattern)
  86.  
  87.      Range, BEGIN and END patterns cannot be combined with  other
  88.      patterns.   One,  but  not  both, of _p_a_t_t_e_r_n {_a_c_t_i_o_n} can be
  89.      omitted.   If {_a_c_t_i_o_n} is omitted it is implicitly  {  print
  90.      }.   If  _p_a_t_t_e_r_n  is omitted, then it is implicitly matched.
  91.      BEGIN and END patterns require an action.
  92.  
  93.      Statements are terminated by newlines, semi-colons or  both.
  94.      Groups  of  statements  such  as  actions or loop bodies are
  95.      blocked via { ... } as in C.  The last statement in a  block
  96.      doesn't  need a terminator.  Blank lines have no meaning; an
  97.      empty statement is terminated with a semi-colon. Long state-
  98.      ments can be continued with a backslash, \.  A statement can
  99.      be broken without a backslash after a comma, left brace, &&,
  100.      ||,  do,  else, the right parenthesis of an if, while or for
  101.      statement, and the right parenthesis of a  function  defini-
  102.      tion.   A comment starts with # and extends to, but does not
  103.      include the end of line.
  104.  
  105.      The following statements control program flow inside blocks.
  106.  
  107.           if ( _e_x_p_r ) _s_t_a_t_e_m_e_n_t
  108.  
  109.           if ( _e_x_p_r ) _s_t_a_t_e_m_e_n_t else _s_t_a_t_e_m_e_n_t
  110.  
  111.           while ( _e_x_p_r ) _s_t_a_t_e_m_e_n_t
  112.  
  113.           do _s_t_a_t_e_m_e_n_t while ( _e_x_p_r )
  114.  
  115.           for ( _o_p_t__e_x_p_r ; _o_p_t__e_x_p_r ; _o_p_t__e_x_p_r ) _s_t_a_t_e_m_e_n_t
  116.  
  117.           for ( _v_a_r in _a_r_r_a_y ) _s_t_a_t_e_m_e_n_t
  118.  
  119.           continue
  120.  
  121.           break
  122.  
  123.   2. Data types, conversion and comparison
  124.      There are two basic data types, numeric and string.  Numeric
  125.      constants  can  be integer like -2, decimal like 1.08, or in
  126.  
  127.  
  128.  
  129. Version 1.0         Last change: Sep 14 1991                    2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MAWK(1)                   USER COMMANDS                   MAWK(1)
  137.  
  138.  
  139.  
  140.      scientific notation like -1.1e4 or .28E-3.  All numbers  are
  141.      represented  internally  and  all  computations  are done in
  142.      floating point arithmetic.  So for example,  the  expression
  143.      0.2e2 == 20 is true and true is represented as 1.0.
  144.  
  145.      String constants are enclosed in double quotes.
  146.  
  147.            "This is a string with a newline at the end.\n"
  148.  
  149.      Strings can be continued across a line by escaping  (\)  the
  150.      newline.  The following escape sequences are recognized.
  151.  
  152.           \\        \
  153.           \"        "
  154.           \a        alert, ascii 7
  155.           \b        backspace, ascii 8
  156.           \t        tab, ascii 9
  157.           \n        newline, ascii 10
  158.           \v        vertical tab, ascii 11
  159.           \f        formfeed, ascii 12
  160.           \r        carriage return, ascii 13
  161.           \ddd      1, 2 or 3 octal digits for ascii ddd
  162.           \xhh      1 or 2 hex digits for ascii  hh
  163.  
  164.      If you escape any other character \c, you get \c, i.e., mawk
  165.      ignores the escape.
  166.  
  167.      There are really three basic data types; the third is _n_u_m_b_e_r
  168.      _a_n_d _s_t_r_i_n_g which has both a numeric value and a string value
  169.      at  the  same  time.   User  defined  variables  come   into
  170.      existence when first referenced and are initialized to _n_u_l_l,
  171.      a number and string value which  has  numeric  value  0  and
  172.      string  value  "".  Non-trivial number and string typed data
  173.      come from input and are typically stored  in  fields.   (See
  174.      section 4).
  175.  
  176.      The type of an expression is determined by its  context  and
  177.      automatic type conversion occurs if needed.  For example, to
  178.      evaluate the statements
  179.  
  180.           y = x + 2  ;  z = x  "hello"
  181.  
  182.      The value stored in variable y will be typed numeric.  If  x
  183.      is  not  numeric,  the  value  taken  from x is converted to
  184.      numeric before it is added to 2 and stored in y.  The  value
  185.      stored  in variable z will be typed string, and the value of
  186.      x will be converted to string if necessary and  concatenated
  187.      with "hello".  (Of course, the value and type stored in x is
  188.      not changed by any conversions.) A string expression is con-
  189.      verted  to  numeric using its longest numeric prefix as with
  190.      _a_t_o_f(3).  A numeric expression is  converted  to  string  by
  191.      replacing  _e_x_p_r  with sprintf( OFMT, _e_x_p_r).  Sprintf() is an
  192.  
  193.  
  194.  
  195. Version 1.0         Last change: Sep 14 1991                    3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. MAWK(1)                   USER COMMANDS                   MAWK(1)
  203.  
  204.  
  205.  
  206.      AWK  built-in   that   duplicates   the   functionality   of
  207.      _s_p_r_i_n_t_f(3).   Explicit  type conversions can be forced, _e_x_p_r
  208.      "" is string and _e_x_p_r+0 is numeric.
  209.  
  210.      To evaluate,  _e_x_p_r1  rel-op  _e_x_p_r2,  if  both  operands  are
  211.      numeric or number and string then the comparison is numeric;
  212.      if both operands are string the comparison is string; if one
  213.      operand  is  string, the non-string operand is converted and
  214.      the comparison is string.  The result is numeric,  1  or  0.
  215.      In boolean contexts such as, if ( _e_x_p_r ) _s_t_a_t_e_m_e_n_t, a string
  216.      expression evaluates true if and only if it is not the empty
  217.      string ""; otherwise if and only if not numerically zero.
  218.  
  219.   3. Regular expressions
  220.      In the AWK language, records, fields and strings  are  often
  221.      tested  for  matching a _r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n.  Regular expres-
  222.      sions are enclosed in slashes, and
  223.  
  224.           _e_x_p_r ~ /_r/
  225.  
  226.      is an AWK expression that evaluates to 1 if  _e_x_p_r  "matches"
  227.      _r,  which means a substring of _e_x_p_r is in the set of strings
  228.      defined by _r.  With no match the expression evaluates to  0;
  229.      replacing ~ with the "not match" operator, !~ , reverses the
  230.      meaning.  As a pattern,
  231.  
  232.           /_r/ { _a_c_t_i_o_n }
  233.  
  234.      is the same as
  235.  
  236.           $0 ~ /_r/ { _a_c_t_i_o_n }
  237.  
  238.      and for each input record that matches  _r,  _a_c_t_i_o_n  is  exe-
  239.      cuted.
  240.  
  241.      AWK uses extended regular expressions as with _e_g_r_e_p(1).  The
  242.      regular  expression metacharacters, i.e., those with special
  243.      meaning in regular expressions are
  244.  
  245.            ^ $ . [ ] | ( ) * + ?
  246.  
  247.      Regular expressions are built up from characters as follows:
  248.  
  249.           _c            matches any non-metacharacter _c.
  250.  
  251.           \_c           matches a character defined  by  the  same
  252.                        escape  sequences used in string constants
  253.                        or the literal character _c if \_c is not an
  254.                        escape sequence.
  255.  
  256.           .            matches any character (including newline).
  257.  
  258.  
  259.  
  260.  
  261. Version 1.0         Last change: Sep 14 1991                    4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. MAWK(1)                   USER COMMANDS                   MAWK(1)
  269.  
  270.  
  271.  
  272.           ^            matches the front of a string.
  273.  
  274.           $            matches the back of a string.
  275.  
  276.           [c1c2c3...]  matches  any  character   in   the   class
  277.                        c1c2c3...  .  An interval of characters is
  278.                        denoted c1-c2 inside a class [...].
  279.  
  280.           [^c1c2c3...] matches any character  not  in  the  class
  281.                        c1c2c3...
  282.  
  283.      Regular expressions are built up from other regular  expres-
  284.      sions as follows:
  285.  
  286.           _r1_r2 matches _r1 followed immediately by _r2  (concatena-
  287.                tion).
  288.  
  289.           _r1 | _r2
  290.                matches _r1 or _r2 (alternation).
  291.  
  292.           _r*   matches _r repeated zero or more times.
  293.  
  294.           _r+   matches _r repeated one or more times.
  295.  
  296.           _r?   matches _r zero or once.
  297.  
  298.           (_r)  matches _r, providing grouping.
  299.  
  300.      The increasing precedence of operators is alternation,  con-
  301.      catenation and unary (*, + or ?).
  302.  
  303.      For example,
  304.  
  305.           /^[_a-zA-Z][_a-zA-Z0-9]*$/  and
  306.           /^[-+]?([0-9]+\.?|\.[0-9])[0-9]*([eE][-+]?[0-9]+)?$/
  307.  
  308.      are matched by AWK identifiers  and  AWK  numeric  constants
  309.      respectively.   Note  that  . has to be escaped to be recog-
  310.      nized as a decimal point, and that  metacharacters  are  not
  311.      special inside character classes.
  312.  
  313.      Any expression can be used on the right hand side of  the  ~
  314.      or !~ operators or passed to a built-in that expects a regu-
  315.      lar expression.  If needed, it is converted  to  string  and
  316.      then interpreted as a regular expression.  For example,
  317.  
  318.           BEGIN { identifier = "[_a-zA-Z][_a-zA-Z0-9]*" }
  319.  
  320.           $0 ~ "^" identifier
  321.  
  322.      prints all lines that start with an AWK identifier.
  323.  
  324.  
  325.  
  326.  
  327. Version 1.0         Last change: Sep 14 1991                    5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. MAWK(1)                   USER COMMANDS                   MAWK(1)
  335.  
  336.  
  337.  
  338.      mawk recognizes the  empty  regular  expression,  //,  which
  339.      matches  the empty string and hence is matched by any string
  340.      at the front, back and between every character.   For  exam-
  341.      ple,
  342.  
  343.           echo  abc | mawk { gsub(//, "X") ; print }
  344.           XaXbXcX
  345.  
  346.  
  347.   4. Records and fields
  348.      Records are read in one at a time, and stored in  the  _f_i_e_l_d
  349.      variable  $0.   The  record  is  split into _f_i_e_l_d_s which are
  350.      stored in $1, $2, ..., $NF.  The built-in variable NF is set
  351.      to  the  number of fields, and NR and FNR are incremented by
  352.      1.  Fields above $NF are set to "".
  353.  
  354.      Assignment to $0 causes the fields and NF to be  recomputed.
  355.      Assignment to NF or to a field causes $0 to be reconstructed
  356.      using OFS.  Assignment to a field with  index  greater  than
  357.      NF, increases NF and causes $0 to be reconstructed.
  358.  
  359.      Data input stored in fields is  string,  unless  the  entire
  360.      field  has  numeric  form  and  then  the type is number and
  361.      string.  For example,
  362.  
  363.           echo 24 24E |
  364.           mawk '{ print($1>100, $1>"100", $2>100, $2>"100") }'
  365.           0 1 1 1
  366.  
  367.      $0 and $2 are string and $1 is number and string.  The first
  368.      comparison  is  numeric,  the second is string, the third is
  369.      string (100 is converted to "100"), and the last is string.
  370.  
  371.   5. Expressions and operators
  372.      The expression syntax is similar to C.  Primary  expressions
  373.      are  numeric constants, string constants, variables, fields,
  374.      arrays and functions. The identifier for a  variable,  array
  375.      or  function can be a sequence of letters, digits and under-
  376.      scores, that does not start with a digit.  Variables are not
  377.      declared;  they exist when first referenced and are initial-
  378.      ized to _n_u_l_l.
  379.  
  380.      New expressions are composed with the following operators in
  381.      order of increasing precedence.
  382.  
  383.           _a_s_s_i_g_n_m_e_n_t          =  +=  -=  *=  /=  %=  ^=
  384.           _c_o_n_d_i_t_i_o_n_a_l         ?  :
  385.           _l_o_g_i_c_a_l _o_r          ||
  386.           _l_o_g_i_c_a_l _a_n_d         &&
  387.           _a_r_r_a_y _m_e_m_b_e_r_s_h_i_p    in
  388.           _m_a_t_c_h_i_n_g       ~   !~
  389.           _r_e_l_a_t_i_o_n_a_l          <  >   <=  >=  ==  !=
  390.  
  391.  
  392.  
  393. Version 1.0         Last change: Sep 14 1991                    6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. MAWK(1)                   USER COMMANDS                   MAWK(1)
  401.  
  402.  
  403.  
  404.           _c_o_n_c_a_t_e_n_a_t_i_o_n       (no explicit operator)
  405.           _a_d_d _o_p_s             +  -
  406.           _m_u_l _o_p_s             *  /  %
  407.           _u_n_a_r_y               +  -
  408.           _l_o_g_i_c_a_l _n_o_t         !
  409.           _e_x_p_o_n_e_n_t_i_a_t_i_o_n      ^
  410.           _i_n_c _a_n_d _d_e_c         ++ -- (both post and pre)
  411.           _f_i_e_l_d               $
  412.  
  413.      Assignment, conditional and exponentiation  associate  right
  414.      to  left;  the other operators associate left to right.  Any
  415.      expression can be parenthesized.
  416.  
  417.   6. Arrays
  418.      Awk provides one-dimensional  arrays.   Array  elements  are
  419.      expressed as _a_r_r_a_y[_e_x_p_r].  Initially an array is empty; ele-
  420.      ments exist when first accessed.   An  expression,  _e_x_p_r  in
  421.      _a_r_r_a_y evaluates to 1 if _a_r_r_a_y[_e_x_p_r] exists, else to 0.
  422.  
  423.      There is a form of the for statement that  loops  over  each
  424.      element of an array.
  425.  
  426.           for ( _v_a_r in _a_r_r_a_y ) _s_t_a_t_e_m_e_n_t
  427.  
  428.      sets _v_a_r to each element of _a_r_r_a_y  and  executes  _s_t_a_t_e_m_e_n_t.
  429.      The order of execution is not defined.
  430.  
  431.      The statement, delete _a_r_r_a_y[_e_x_p_r], causes _a_r_r_a_y[_e_x_p_r] not to
  432.      exist.
  433.  
  434.      Multidimensional arrays are synthesized  with  concatenation
  435.      using  the  built-in variable SUBSEP.  _a_r_r_a_y[_e_x_p_r1,_e_x_p_r2] is
  436.      equivalent to _a_r_r_a_y[_e_x_p_r1 SUBSEP _e_x_p_r2].  Testing for a mul-
  437.      tidimensional element uses a parenthesized index, such as
  438.  
  439.           if ( (i, j) in A )  print A[i, j]
  440.  
  441.  
  442.   7. Builtin-variables
  443.      The following variables are built-in and initialized  before
  444.      program execution.
  445.  
  446.           ARGC      number of command line arguments.
  447.  
  448.           ARGV      array of command line arguments, 0..ARGC-1.
  449.  
  450.           FILENAME  name of the current input file.
  451.  
  452.           FNR       current record number in FILENAME.
  453.  
  454.           FS        splits  records  into  fields  as  a  regular
  455.                     expression.
  456.  
  457.  
  458.  
  459. Version 1.0         Last change: Sep 14 1991                    7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. MAWK(1)                   USER COMMANDS                   MAWK(1)
  467.  
  468.  
  469.  
  470.           NF        number of fields in the current record.
  471.  
  472.           NR        current record  number  in  the  total  input
  473.                     stream.
  474.  
  475.           OFMT      format  for  printing  numbers;  initially  =
  476.                     "%.6g".
  477.  
  478.           OFS       inserted between fields on output,  initially
  479.                     = " ".
  480.  
  481.           ORS       terminates each record on output, initially =
  482.                     "\n".
  483.  
  484.           RLENGTH   length set by the last call to  the  built-in
  485.                     function, match().
  486.  
  487.           RS        input record separator, initially = "\n".
  488.  
  489.           RSTART    index set by the last call to match().
  490.  
  491.           SUBSEP    used to build multiple array subscripts, ini-
  492.                     tially = "\034".
  493.  
  494.   8. Built-in functions
  495.      String functions
  496.  
  497.           gsub(_r,_s,_t)  gsub(_r,_s)
  498.                Global  substitution,  every  match   of   regular
  499.                expression  _r  in variable _t is replaced by string
  500.                _s.  The number of replacements is returned.  If  _t
  501.                is  omitted,  $0 is used.  An & in the replacement
  502.                string _s is replaced by the matched  substring  of
  503.                _t.  \& puts a literal & in the replacement string.
  504.  
  505.           index(_s,_t)
  506.                If _t is a substring of _s, then the position  where
  507.                _t  starts  is  returned,  else 0 is returned.  The
  508.                first character of _s is in position 1.
  509.  
  510.           length(_s)  length
  511.                Returns the length of string _s; without  an  argu-
  512.                ment, returns the length of $0.
  513.  
  514.           match(_s,_r)
  515.                Returns the index of the first  longest  match  of
  516.                regular expression _r in string _s.  Returns 0 if no
  517.                match.  As a side effect, RSTART  is  set  to  the
  518.                return value.  RLENGTH is set to the length of the
  519.                match or -1 if no match.  If the empty  string  is
  520.                matched, RLENGTH is set to 0, and 1 is returned if
  521.                the match is at  the  front,  and  length(_s)+1  is
  522.  
  523.  
  524.  
  525. Version 1.0         Last change: Sep 14 1991                    8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. MAWK(1)                   USER COMMANDS                   MAWK(1)
  533.  
  534.  
  535.  
  536.                returned if the match is at the back.
  537.  
  538.           split(_s,_A,_r)  split(_s,_A)
  539.                String _s is split into fields by  regular  expres-
  540.                sion  _r  and  the  fields are loaded into array _A.
  541.                The number of fields is returned.  See section  11
  542.                below  for  more  detail.   If _r is omitted, FS is
  543.                used.
  544.  
  545.           sprintf(_f_o_r_m_a_t,_e_x_p_r-_l_i_s_t)
  546.                Returns  a  string  constructed   from   _e_x_p_r-_l_i_s_t
  547.                according  to  _f_o_r_m_a_t.   See  the  description  of
  548.                printf() below.
  549.  
  550.           sub(_r,_s,_t)  sub(_r,_s)
  551.                Single substitution, same as gsub() except at most
  552.                one substitution.
  553.  
  554.           substr(_s,_i,_n)  substr(_s,_i)
  555.                Returns the substring of  string  _s,  starting  at
  556.                index _i, of length _n.  If _n is omitted, the suffix
  557.                of _s, starting at _i is returned.
  558.  
  559.      Arithmetic functions
  560.  
  561.           atan2(_y,_x)     Arctan of _y/_x between -pi and pi.
  562.  
  563.           cos(_x)         Cosine function, _x in radians.
  564.  
  565.           exp(_x)         Exponential function.
  566.  
  567.           int(_x)         Returns _x truncated towards zero.
  568.  
  569.           log(_x)         Natural logarithm.
  570.  
  571.           rand()         Returns a random number between zero and one.
  572.  
  573.           sin(_x)         Sine function, _x in radians.
  574.  
  575.           sqrt(_x)        Returns square root of _x.
  576.  
  577.           srand(_e_x_p_r)  srand()
  578.                Seeds the random number generator, using the clock
  579.                if  _e_x_p_r  is omitted, and returns the value of the
  580.                previous seed.  mawk seeds the random number  gen-
  581.                erator  from  the  clock at startup so there is no
  582.                real need to call srand().  Srand(_e_x_p_r) is  useful
  583.                for repeating pseudo random sequences.
  584.  
  585.   9. Input and output
  586.      There are two output statements, print and printf.
  587.  
  588.  
  589.  
  590.  
  591. Version 1.0         Last change: Sep 14 1991                    9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. MAWK(1)                   USER COMMANDS                   MAWK(1)
  599.  
  600.  
  601.  
  602.           print
  603.                writes $0  ORS to standard output.
  604.  
  605.           print _e_x_p_r1, _e_x_p_r2, ..., _e_x_p_rn
  606.                writes _e_x_p_r1 OFS _e_x_p_r2 OFS ... _e_x_p_rn ORS to  stan-
  607.                dard output.
  608.  
  609.           printf _f_o_r_m_a_t, _e_x_p_r-_l_i_s_t
  610.                duplicates the printf C library  function  writing
  611.                to standard output.  Supported conversions are %c,
  612.                %d, %e, %f, %g, %o and %x. -, width and .prec  are
  613.                supported.   Dynamic  widths  can  be  built using
  614.                string operations.
  615.  
  616.      The output of print and printf can be redirected to  a  file
  617.      or  command by appending > _f_i_l_e, >> _f_i_l_e or | _c_o_m_m_a_n_d to the
  618.      end of the print statement.  Redirection opens _f_i_l_e or  _c_o_m_-
  619.      _m_a_n_d  only  once,  subsequent  redirections  append  to  the
  620.      already open stream.  The argument list to print  or  printf
  621.      can optionally be enclosed in parentheses.
  622.  
  623.      The input function getline has the following variations.
  624.  
  625.           getline
  626.                reads $0, updates the fields, NF, NR and FNR.
  627.  
  628.           getline < _f_i_l_e
  629.                reads $0 from _f_i_l_e, updates the fields and NF.
  630.  
  631.           getline _v_a_r
  632.                reads the next record into  _v_a_r,  updates  NR  and
  633.                FNR.
  634.  
  635.           getline _v_a_r < _f_i_l_e
  636.                reads the next record of _f_i_l_e into _v_a_r.
  637.  
  638.            _c_o_m_m_a_n_d | getline
  639.                pipes a record from _c_o_m_m_a_n_d into  $0  and  updates
  640.                the fields and NF.
  641.  
  642.            _c_o_m_m_a_n_d | getline _v_a_r
  643.                pipes a record from _c_o_m_m_a_n_d into _v_a_r.
  644.  
  645.      Getline returns 0 on end-of-file, -1 on error, otherwise  1.
  646.      _C_o_m_m_a_n_d is executed by /bin/sh.
  647.  
  648.      The function close(_e_x_p_r) closes the file or pipe  associated
  649.      with  _e_x_p_r.  Close returns 0 or -1 if _e_x_p_r is not associated
  650.      with an open stream.  Close() is used to reread  a  file  or
  651.      command,  make  sure the other end of an output pipe is fin-
  652.      ished or conserve file resources.
  653.  
  654.  
  655.  
  656.  
  657. Version 1.0         Last change: Sep 14 1991                   10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. MAWK(1)                   USER COMMANDS                   MAWK(1)
  665.  
  666.  
  667.  
  668.      The function system(_e_x_p_r) uses /bin/sh to execute  _e_x_p_r  and
  669.      returns the exit status of the command _e_x_p_r.
  670.  
  671.   10. User defined functions
  672.      The syntax for a user defined function is
  673.  
  674.           function name( _a_r_g_s ) { _s_t_a_t_e_m_e_n_t_s }
  675.  
  676.      The function body can contain a return statement
  677.  
  678.           return _o_p_t__e_x_p_r
  679.  
  680.      A return statement is not required. Function  calls  may  be
  681.      nested  or  recursive.   Functions are passed expressions by
  682.      value and arrays by reference.   Extra  arguments  serve  as
  683.      local  variables  and are initialized to _n_u_l_l.  For example,
  684.      csplit(_s,_A) puts each  character  of  _s  into  array  _A  and
  685.      returns the length of _s.
  686.  
  687.           function csplit(s, A,    n, i)
  688.           {
  689.             n = length(s)
  690.             for( i = 1 ; i <= n ; i++ ) A[i] = substr(s, i, 1)
  691.             return n
  692.           }
  693.  
  694.      Putting extra space between passed arguments and local vari-
  695.      ables  is  conventional.  Functions can be referenced before
  696.      they are defined, but the function name and the '('  of  the
  697.      arguments must touch to avoid confusion with concatenation.
  698.  
  699.   11. Splitting strings, records and files
  700.      Awk programs use the same algorithm to  split  strings  into
  701.      arrays  with  split(),  and records into fields on FS.  mawk
  702.      uses essentially the same  algorithm  to  split  files  into
  703.      records on RS.
  704.  
  705.      Split(_e_x_p_r,_A,_s_e_p) works as follows:
  706.  
  707.           (1)  If _s_e_p is omitted, it is replaced by FS.  _S_e_p  can
  708.                be  an expression or regular expression.  If it is
  709.                an expression of non-string type, it is  converted
  710.                to string.
  711.  
  712.           (2)  If _s_e_p = " " (a single  space),  then  <SPACE>  is
  713.                trimmed  from  the front and back of _e_x_p_r, and _s_e_p
  714.                becomes <SPACE>.  mawk defines <SPACE> as the reg-
  715.                ular  expression  /[ \t\r\n]+/.  Otherwise  _s_e_p is
  716.                treated  as  a  regular  expression,  except  that
  717.                meta-characters are ignored for a string of length
  718.                1, e.g., split(x, A, "*") and  split(x,  A,  /\*/)
  719.                are the same.
  720.  
  721.  
  722.  
  723. Version 1.0         Last change: Sep 14 1991                   11
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. MAWK(1)                   USER COMMANDS                   MAWK(1)
  731.  
  732.  
  733.  
  734.           (3)  If _e_x_p_r is not string, it is converted to  string.
  735.                If  _e_x_p_r  is  then  the  empty  string "", split()
  736.                returns 0 and  _A  is  unchanged.   Otherwise,  all
  737.                non-overlapping,  non-null  and longest matches of
  738.                _s_e_p in _e_x_p_r, separate _e_x_p_r into fields  which  are
  739.                loaded  into  _A.   The  fields are placed in A[1],
  740.                A[2], ..., A[n] and split() returns n, the  number
  741.                of fields which is the number of matches plus one.
  742.                Data placed in  _A  that  looks  numeric  is  typed
  743.                number and string.
  744.  
  745.      Splitting records into fields  works  the  same  except  the
  746.      pieces  are loaded into $1, $2,..., $NF.  If $0 is empty, NF
  747.      is set to 0 and all $i to "".
  748.  
  749.      mawk splits files into records by the  same  algorithm,  but
  750.      with  the  slight  difference that RS is really a terminator
  751.      instead of a separator. (ORS is really a terminator too).
  752.  
  753.           E.g., if FS = ":+" and $0 = "a::b:" , then NF =  3  and
  754.           $1  =  "a", $2 = "b" and $3 = "", but if "a::b:" is the
  755.           contents of an input file and RS = ":+", then there are
  756.           two records "a" and "b".
  757.  
  758.      RS = " " is not special.
  759.  
  760.   12. Multi-line records
  761.      Since mawk interprets RS as a regular expression, multi-line
  762.      records  are  easy.  Setting RS = "\n\n+", makes one or more
  763.      blank lines separate records.  If FS = "  "  (the  default),
  764.      then single newlines, by the rules for <SPACE> above, become
  765.      space and single newlines are field separators.
  766.  
  767.           For example, if a file is "a b\nc\n\n",  RS  =  "\n\n+"
  768.           and  FS  =  " ", then there is one record "a b\nc" with
  769.           three fields "a", "b" and "c".   Changing  FS  =  "\n",
  770.           gives two fields "a b" and "c"; changing FS = "", gives
  771.           one field identical to the record.
  772.  
  773.      If you want lines with  spaces  or  tabs  to  be  considered
  774.      blank,  set  RS  =  "\n([ \t]*\n)+".  For compatibility with
  775.      other awks, setting RS = "" has the same effect on determin-
  776.      ing  records  as  RS  = "\n\n+".  (This interpretation makes
  777.      mawk picky that the input not start  with  blank  lines  and
  778.      that  the  last record is fully terminated with at least two
  779.      newlines.)
  780.  
  781.      Most of the time when you change RS for multi-line  records,
  782.      you  will  also  want  to change ORS to "\n\n" so the record
  783.      spacing is preserved on output.
  784.  
  785.  
  786.  
  787.  
  788.  
  789. Version 1.0         Last change: Sep 14 1991                   12
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. MAWK(1)                   USER COMMANDS                   MAWK(1)
  797.  
  798.  
  799.  
  800.   13. Program execution
  801.      This section  describes  the  order  of  program  execution.
  802.      First  ARGC is set to the total number of command line argu-
  803.      ments passed to the execution phase of the program.  ARGV[0]
  804.      is  set  the  name  of  the  AWK interpreter and ARGV[1] ...
  805.      ARGV[ARGC-1] holds  the  remaining  command  line  arguments
  806.      exclusive of options and program source.  For example with
  807.  
  808.           mawk  -f  prog  v=1  A  t=hello  B
  809.  
  810.      ARGC = 5 with ARGV[0] = "mawk", ARGV[1] = "v=1",  ARGV[2]  =
  811.      "A", ARGV[3] = "t=hello" and ARGV[4] = "B".
  812.  
  813.      Next, each BEGIN block is executed in order.  If the program
  814.      consists  entirely  of  BEGIN  blocks,  then  execution ter-
  815.      minates, else an input stream is opened and  execution  con-
  816.      tinues.  If ARGC equals 1, the input stream is set to stdin,
  817.      else  the command line arguments  ARGV[1]  ...  ARGV[ARGC-1]
  818.      are examined for a file argument.
  819.  
  820.      The command line arguments  divide  into  three  sets:  file
  821.      arguments,  assignment  arguments  and empty strings "".  An
  822.      assignment has the form  _v_a_r=_s_t_r_i_n_g.   When  an  ARGV[i]  is
  823.      examined  as  a possible file argument, if it is empty it is
  824.      skipped; if it is an assignment argument, the assignment  to
  825.      _v_a_r  takes  place  and  i  skips  to the next argument; else
  826.      ARGV[i] is opened for input.  If it fails to open, execution
  827.      terminates with exit code 1.  If no command line argument is
  828.      a file argument, then input comes from stdin.  Getline in  a
  829.      BEGIN  action  opens  input.  "-" as a file argument denotes
  830.      stdin.
  831.  
  832.      Once an input stream is open, each input  record  is  tested
  833.      against  each  _p_a_t_t_e_r_n,  and  if  it matches, the associated
  834.      _a_c_t_i_o_n is executed.  An expression pattern matches if it  is
  835.      boolean  true (see the end of section 2).  A regular expres-
  836.      sion pattern matches if $0 matches the  regular  expression.
  837.      A  BEGIN pattern matches before any input has been read, and
  838.      an END pattern matches after all input  has  been  read.   A
  839.      range  pattern, _p_a_t1,_p_a_t2 , matches every record between the
  840.      match of _p_a_t1 and the match _p_a_t2 inclusively.
  841.  
  842.      When end of file occurs on the input stream,  the  remaining
  843.      command line arguments are examined for a file argument, and
  844.      if there is one it is opened, else the END _p_a_t_t_e_r_n  is  con-
  845.      sidered matched and all END _a_c_t_i_o_n_s are executed.
  846.  
  847.      In the example, the assignment v=1  takes  place  after  the
  848.      BEGIN  _a_c_t_i_o_n_s  are  executed,  and  the data placed in v is
  849.      typed number and string.  Input is then read  from  file  A.
  850.      On  end  of file A, t is set to the string "hello", and B is
  851.      opened for input.  On end of file B,  the  END  _a_c_t_i_o_n_s  are
  852.  
  853.  
  854.  
  855. Version 1.0         Last change: Sep 14 1991                   13
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862. MAWK(1)                   USER COMMANDS                   MAWK(1)
  863.  
  864.  
  865.  
  866.      executed.
  867.  
  868.      Program flow at the _p_a_t_t_e_r_n {_a_c_t_i_o_n} level  can  be  changed
  869.      with the
  870.  
  871.           next   and
  872.           exit  _o_p_t__e_x_p_r
  873.  
  874.      statements.  A next statement causes the next  input  record
  875.      to  be  read  and  pattern testing to restart with the first
  876.      _p_a_t_t_e_r_n {_a_c_t_i_o_n} pair in the  program.   An  exit  statement
  877.      causes  immediate  execution  of  the END actions or program
  878.      termination if there are none or if the exit  occurs  in  an
  879.      END action.  The _o_p_t__e_x_p_r sets the exit value of the program
  880.      unless overridden by a later exit or subsequent error.
  881.  
  882.  
  883. EXAMPLES
  884.      1. emulate cat.
  885.  
  886.           { print }
  887.  
  888.      2. emulate wc.
  889.  
  890.           { chars += length($0) + 1  # add one for the \n
  891.             words += NF
  892.           }
  893.  
  894.           END{ print NR, words, chars }
  895.  
  896.      3. count the number of unique "real words".
  897.  
  898.           BEGIN { FS = "[^A-Za-z]+" }
  899.  
  900.           { for(i = 1 ; i <= NF ; i++)  word[$i] = "" }
  901.  
  902.           END { delete word[""]
  903.                 for ( i in word )  cnt++
  904.                 print cnt
  905.           }
  906.  
  907.      4. sum the second field of every record based on  the  first
  908.      field.
  909.  
  910.           $1 ~ /credit|gain/ { sum += $2 }
  911.           $1 ~ /debit|loss/  { sum -= $2 }
  912.  
  913.           END { print sum }
  914.  
  915.      5. sort a file, comparing as string
  916.  
  917.           { line[NR] = $0 "" }  # make sure of comparison type
  918.  
  919.  
  920.  
  921. Version 1.0         Last change: Sep 14 1991                   14
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928. MAWK(1)                   USER COMMANDS                   MAWK(1)
  929.  
  930.  
  931.  
  932.                           # in case some lines look numeric
  933.  
  934.           END {  isort(line, NR)
  935.             for(i = 1 ; i <= NR ; i++) print line[i]
  936.           }
  937.  
  938.           #insertion sort of A[1..n]
  939.           function isort( A, n,    i, j, hold)
  940.           {
  941.             for( i = 2 ; i <= n ; i++)
  942.             {
  943.               hold = A[j = i]
  944.               while ( A[j-1] > hold )
  945.               { j-- ; A[j+1] = A[j] }
  946.               A[j] = hold
  947.             }
  948.             # sentinel A[0] = "" will be created if needed
  949.           }
  950.  
  951.  
  952.  
  953. COMPATIBILITY ISSUES
  954.      mawk and SystemVR3 nawk (new awk) implement the AWK language
  955.      as  described  in the AWK book.  SystemVR4 nawk, with influ-
  956.      ence from GNU gawk, added a few features that are now speci-
  957.      fied in the draft 11.1 POSIX standard for awk, most notably,
  958.      functions  toupper()  and  tolower(),  and  access  to   the
  959.      environment through an array, ENVIRON[].
  960.  
  961.      With mawk, the following are all equivalent,
  962.  
  963.           x ~ /a\+b/    x ~ "a\+b"     x ~ "a\\+b"
  964.  
  965.      The strings get scanned twice, once as string  and  once  as
  966.      regular  expression.   On  the string scan, mawk ignores the
  967.      escape on non-escape characters while the AWK book advocates
  968.      _\_c be recognized as _c which necessitates the double escaping
  969.      of meta-characters in strings.  For programs that  must  run
  970.      under  a  variety  of awks, the more portable but less read-
  971.      able, double escape should be used.
  972.  
  973.      POSIX AWK is oriented to operate on files a line at a  time.
  974.      RS can be changed from "\n" to another single character, but
  975.      it is hard to find any use for this - there are no  examples
  976.      in  the AWK book.  By convention, RS = "", makes one or more
  977.      blank lines separate records, allowing  multi-line  records.
  978.      When RS = "", "\n" is always a field separator regardless of
  979.      the value in FS.
  980.  
  981.      mawk, on the other hand, allows RS to be a  regular  expres-
  982.      sion.  When "\n" appears in records, it is treated as space,
  983.      and FS always determines fields.  RS =  ""  is  treated  the
  984.  
  985.  
  986.  
  987. Version 1.0         Last change: Sep 14 1991                   15
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994. MAWK(1)                   USER COMMANDS                   MAWK(1)
  995.  
  996.  
  997.  
  998.      same as RS = "\n\n+".
  999.  
  1000.      Removing the line at a time paradigm can make some  programs
  1001.      simplier  and  can  often improve performance.  For example,
  1002.      redoing example 3 from above,
  1003.  
  1004.           BEGIN { RS = "[^A-Za-z]+" }
  1005.  
  1006.           { word[ $0 ] = "" }
  1007.  
  1008.           END { delete  word[ "" ]
  1009.             for( i in word )  cnt++
  1010.             print cnt
  1011.           }
  1012.  
  1013.      counts the number of unique words  by  making  each  word  a
  1014.      record.   On  moderate  size  files,  mawk executes twice as
  1015.      fast, because of the simplified inner loop.
  1016.  
  1017.      The following program replaces  each  comment  by  a  single
  1018.      space in a C program file,
  1019.  
  1020.           BEGIN {
  1021.             RS = "/\*([^*]|\*+[^/*])*\*+/"
  1022.                # comment is record separator
  1023.             ORS = " "
  1024.             getline  hold
  1025.             }
  1026.  
  1027.             { print hold ; hold = $0 }
  1028.  
  1029.             END { printf "%s" , hold }
  1030.  
  1031.      Buffering one record is needed to avoid terminating the last
  1032.      record with a space.
  1033.  
  1034.      Finally, here is how mawk handles exceptional cases not dis-
  1035.      cussed  in the AWK book or the POSIX draft.  It is unsafe to
  1036.      assume consistency across awks and safe to skip to the  next
  1037.      section.
  1038.  
  1039.           substr(s, i, n) returns the  characters  of  s  in  the
  1040.           intersection  of the closed interval [1, length(s)] and
  1041.           the half-open interval [i, i+n).  When  this  intersec-
  1042.           tion  is  empty,  the  empty  string  is  returned;  so
  1043.           substr("ABC", 1, 0) = "" and  substr("ABC",  -4,  6)  =
  1044.           "A".
  1045.  
  1046.           Every string, including the empty string,  matches  the
  1047.           empty  string  at  the front so, s ~ // and s ~ "", are
  1048.           always 1 as is match(s, //) and match(s, "").  The last
  1049.           two set RLENGTH to 0.
  1050.  
  1051.  
  1052.  
  1053. Version 1.0         Last change: Sep 14 1991                   16
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060. MAWK(1)                   USER COMMANDS                   MAWK(1)
  1061.  
  1062.  
  1063.  
  1064.           index(s, t) is always the same as match(s, t1) where t1
  1065.           is  the  same  as t with metacharacters escaped.  Hence
  1066.           consistency  with  match  requires  that  index(s,  "")
  1067.           always  returns 1.  Also the condition, index(s,t) != 0
  1068.           if  and  only  t  is  a  substring   of   s,   requires
  1069.           index("","") = 1.
  1070.  
  1071.           If getline encounters end of file, getline var,  leaves
  1072.           var unchanged.  Similarly, on entry to the END actions,
  1073.           $0, the fields and NF have their value  unaltered  from
  1074.           the last record.
  1075.  
  1076.  
  1077. DIAGNOSTICS
  1078.      A previously undiscussed option -D causes mawk  to  _d_u_m_p  to
  1079.      stderr an assembler like listing of its internal representa-
  1080.      tion of the program which is linear byte code for a  virtual
  1081.      stack machine.
  1082.  
  1083.  
  1084. SEE ALSO
  1085.      _e_g_r_e_p (1)
  1086.  
  1087.      Aho, Kernighan and Weinberger, _T_h_e _A_W_K _P_r_o_g_r_a_m_m_i_n_g _L_a_n_g_u_a_g_e,
  1088.      Addison-Wesley Publishing, 1988, (the AWK book), defines the
  1089.      language, opening with a  tutorial  and  advancing  to  many
  1090.      interesting  programs  that  delve  into  issues of software
  1091.      design and analysis relevant to programming in any language.
  1092.  
  1093.      _T_h_e _G_A_W_K _M_a_n_u_a_l, The Free Software Foundation,  1991,  is  a
  1094.      tutorial  and  language  reference that does not attempt the
  1095.      depth of the AWK book and assumes the reader may be a novice
  1096.      programmer. The section on AWK arrays is excellent.  It also
  1097.      discusses POSIX requirements for AWK.
  1098.  
  1099.  
  1100. BUGS
  1101.      mawk cannot handle ascii NUL \0 in the source or data files.
  1102.      You can output NUL using printf with %c, and any other 8 bit
  1103.      character is acceptable input.
  1104.  
  1105.      Implementors of the AWK language  have  shown  a  consistent
  1106.      lack of imagination when naming their programs.
  1107.  
  1108.  
  1109. AUTHOR
  1110.      Mike Brennan (brennan@boeing.com).
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119. Version 1.0         Last change: Sep 14 1991                   17
  1120.  
  1121.  
  1122.  
  1123.